STF-1906: Add phone verification inputs to minFraud by oschwald · Pull Request #6 · maxmind/openapi

oschwald · 2026-10-09T20:50:54Z

Adds three optional inputs to the minFraud request billing and shipping objects: phone_verification_method (delivered_code, network, or other), phone_was_verification_successful (boolean), and phone_verification_time (RFC 3339 date-time). They describe the most recent verification of the phone number. Both objects extend the shared Address schema, so the inputs live there. Risk scoring uses the shipping phone when the billing phone is absent. The request example and the bundled spec include the new fields.

🤖 Generated with Claude Code

Summary by CodeRabbit

New Features
- MinFraud requests can include optional phone-verification details: the method, verification time, and whether the latest verification succeeded. Methods may be network, delivered code, or other.
- Verification times earlier than January 1, 1970, or more than two days in the future are ignored with a warning.
Documentation
- Updated billing and shipping request examples to show successful delivered-code verification.
- Clarified that event timestamps must use RFC 3339 format, include seconds, and specify a UTC designator or numeric timezone offset.

coderabbitai · 2026-10-09T20:51:05Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Advanced
Run ID: 3e31e783-79f9-4e5c-bcaf-ff25aaa9898b

📥 Commits

Reviewing files that changed from the base of the PR and between 25b86c5 and 5f17866.

📒 Files selected for processing: 4

.gitattributes
bundled/minfraud.yaml
components/minfraud-request.yaml
examples/minfraud/request.yaml

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

The MinFraud request schema adds optional phone-verification fields and an RFC 3339 pattern for Event.time. The bundled schema and billing and shipping request examples include the corresponding updates.

Changes: MinFraud request schema

Layer / File(s)	Summary
Request fields and timestamp format `components/minfraud-request.yaml`, `bundled/minfraud.yaml`	The `Address` schema adds optional phone-verification method, time, and success fields. It defines allowed methods and timestamp bounds. `Event.time` gains a pattern requiring seconds and a UTC designator or numeric offset.
Billing and shipping examples, generated-file marking `bundled/minfraud.yaml`, `examples/minfraud/request.yaml`, `.gitattributes`	Billing and shipping examples include delivered-code verification values. `.gitattributes` marks files under `bundled/` as generated.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~10 minutes

Change: Feature

Suggested reviewers: horgh

Merge Risk: ⚪ Minimal · up to 5f178

The request schema, bundled specification, and examples consistently include the new phone-verification inputs. No material merge-blocking risk is identified.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: adding phone verification inputs to minFraud.
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (4 skipped: 4 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

Commit to this branch
Create a new PR

Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{A rabbit checks the timestamp glow
Then marks the fields that schemas show
Two addresses share the date
Three methods join the data plate
The bundled files hop into place}

_{Comment @coderabbitai help to get the list of available commands.}

The minFraud request `billing` and `shipping` objects now accept three optional inputs that describe the most recent verification of the phone number: `phone_verification_method`, `phone_was_verification_successful`, and `phone_verification_time`. Risk scoring uses the shipping phone when the billing phone is absent. Both objects share the `Address` schema, so the inputs live there. The request example and the bundled spec include them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

horgh

Some nits from Claude and a thought from me!

horgh · 2026-10-19T15:39:07Z

+          - `other`: another verification method.
+      phone_verification_time:
+        type: string
+        format: date-time


format: date-time accepts some timestamps that the server rejects. JSON Schema follows RFC 3339, which allows a lowercase t and z and a leap second (:60). The server parses with time.Parse(time.RFC3339, ...), which rejects all of these:

2026-10-01t14:30:00z -> cannot parse "t14:30:00z" as "T" 2026-10-01T14:30:00z -> cannot parse "z" as "Z07:00" 2016-12-31T23:59:60Z -> second out of range

The server then returns INPUT_INVALID and drops the field. A client that validates against this spec does not see the problem until it reads the warning. The Python client PR for the same change uses an uppercase-only pattern, so the spec and that client disagree.

Suggestion: add a pattern that requires an uppercase T and Z, or say in the description that the server requires them and rejects leap seconds. The existing time input has the same gap, so a shared pattern for both fields can fix it in one place.

🤖 Comment by Claude Opus 5.5.

Done in f662b29. Both phone_verification_time and the event time now have a pattern that allows only an uppercase T and Z, seconds 00 to 59, and offsets up to 23:59.

Reply by Claude Opus 5.5 on Greg's behalf.

horgh · 2026-10-19T15:39:07Z

+          - `delivered_code`: a code delivered to the phone, such as by SMS,
+          voice call, or messaging app.
+
+          - `network`: verification through the mobile network operator, such as


The network and other descriptions do not match the docs in dev-site#1775:

Docs: network is "Carrier or SIM-based silent network authentication. No code is sent to the device." The spec says "verification through the mobile network operator", which can also describe flash-call or missed-call checks.

Docs: other includes "flash or missed call verification, or a method you do not know because a third party performed the check". The spec says only "another verification method".

A merchant who uses flash-call verification and reads the spec can send network, but the docs say other. A merchant whose vendor does not report the method can omit the field, but the docs say to send other. Suggest using the docs wording for both values.

🤖 Comment by Claude Opus 5.5.

Done in 4cf5879. The value descriptions now use the dev-site wording.

Reply by Claude Opus 5.5 on Greg's behalf.

horgh · 2026-10-19T15:39:07Z

+          - network
+          - other
+        description: >-
+          The most recent method used to verify the phone number.


This description has two gaps compared to dev-site#1775:

It does not say to omit the field when no verification was attempted. The docs say "Do not include this field if no verification was attempted", and the spec says this for phone_was_verification_successful. Without the rule, a client can send the catch-all other for "not verified".

"The most recent method used to verify the phone number" can read as the method of the most recent successful verification. phone_was_verification_successful can be false, so the three fields must describe the same most recent attempt. The docs say "The method used for the most recent verification attempt".

Suggestion: "The method used for the most recent verification attempt of the phone number. Omit this field if no verification was attempted."

🤖 Comment by Claude Opus 5.5.

Done in 4cf5879, with your suggested text.

Reply by Claude Opus 5.5 on Greg's behalf.

horgh · 2026-10-19T15:39:07Z

+        type: string
+        format: date-time
+        description: >-
+          The date and time of the most recent verification of the phone number,


"The most recent verification of the phone number" can read as the most recent successful verification. A client can then send the time of the last successful check with phone_was_verification_successful: false from a later failed attempt, and the fields describe different events. The docs in dev-site#1775 say "The most recent date and time a verification of the ... phone number was attempted, if known".

Suggestion: say "the most recent verification attempt", and say to omit the field when the time is not known, so that a client does not send a placeholder such as the event time.

🤖 Comment by Claude Opus 5.5.

Done in 4cf5879: "The most recent date and time a verification of the phone number was attempted, if known". Product is still reviewing the dev-site wording, so this can change again.

Reply by Claude Opus 5.5 on Greg's behalf.

horgh · 2026-10-19T15:39:07Z

        description: >-
          The phone number, without the country code. MaxMind strips punctuation
          characters. After that, the number must contain only digits.
+      phone_verification_method:


The real target is specs/minfraud.yaml (info.version: 0.1.0) and CHANGELOG.md, which are not in the diff.

This PR adds three request fields but does not change info.version or add a changelog entry. The README says that info.version follows SemVer and tracks changes to the spec. No tag or release exists yet, so this is fine if 0.1.0 is still unreleased. But mm_website already uses a pseudo-version of this module, so two different minFraud documents will both say 0.1.0. Is the plan to bump to 0.2.0 (with a changelog entry) at the first release, or now?

🤖 Comment by Claude Opus 5.5.

We will leave info.version at 0.1.0. Nothing is tagged or released yet, so the first release sets the version and adds the changelog entry.

Reply by Claude Opus 5.5 on Greg's behalf.

horgh · 2026-10-19T15:39:07Z

    phone_country_code: "1"
    phone_number: 203-000-0000
+    phone_verification_method: delivered_code
+    phone_verification_time: "2026-10-01T14:35:00Z"


Nit: the shipping example uses 2026-10-01T14:35:00Z, but the shipping request example in dev-site#1775 uses 2026-10-01T14:30:00Z. All other example fields match the docs. Suggest using the same value in both PRs (bundled/minfraud.yaml also has 14:35).

🤖 Comment by Claude Opus 5.5.

Done in 30399f3.

Reply by Claude Opus 5.5 on Greg's behalf.

horgh · 2026-10-19T20:02:10Z

          phone_number: 203-000-0000
+          phone_verification_method: delivered_code
+          phone_verification_time: '2026-10-01T14:35:00Z'
+          phone_was_verification_successful: true


I wonder if we could mark this file as generated in git or something so GitHub doesn't display it as a usual diff.

Yeah, maybe we can set the git attributes to do that.

Done in 5f17866: bundled/** linguist-generated=true.

Reply by Claude Opus 5.5 on Greg's behalf.

Match the descriptions on dev.maxmind.com. The method and time describe the most recent verification attempt, not the most recent successful one. The method is omitted when no verification was attempted. The network, delivered_code and other descriptions now give the same examples as the docs, in the same order. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

format: date-time follows RFC 3339, which allows a lowercase "t" and "z" and a leap second. The web service rejects these and ignores the input with a warning. Add a pattern to the event time and the phone verification time that allows only an uppercase "T" and "Z", hours 00 to 23, minutes and seconds 00 to 59, and offsets up to 23:59. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

GitHub then collapses bundled/ in pull request diffs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

oschwald mentioned this pull request Oct 9, 2026

Add email verification inputs to minFraud #7

Draft

oschwald force-pushed the greg/billing-phone-verification-inputs branch from cf60e92 to 444a3ae Compare October 12, 2026 14:56

oschwald changed the title ~~Add billing phone verification inputs to minFraud~~ Add phone verification inputs to minFraud Oct 12, 2026

oschwald force-pushed the greg/billing-phone-verification-inputs branch 2 times, most recently from 34f8da7 to 5f40f16 Compare October 14, 2026 21:36

oschwald force-pushed the greg/billing-phone-verification-inputs branch from 5f40f16 to 25b86c5 Compare October 15, 2026 22:04

oschwald marked this pull request as ready for review October 15, 2026 22:04

Copilot AI balanced review requested due to automatic review settings October 15, 2026 22:04

Copilot AI reviewed Oct 15, 2026

oschwald changed the title ~~Add phone verification inputs to minFraud~~ STF-1906: Add phone verification inputs to minFraud Oct 16, 2026

horgh requested changes Oct 19, 2026

View reviewed changes

oschwald and others added 4 commits October 19, 2026 20:43

Use the same shipping verification time as the dev docs

30399f3

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Mark the bundled specs as generated

5f17866

GitHub then collapses bundled/ in pull request diffs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI balanced review requested due to automatic review settings October 19, 2026 20:48

Copilot AI reviewed Oct 19, 2026

horgh approved these changes Oct 20, 2026

View reviewed changes

horgh merged commit 7e89381 into main Oct 20, 2026
6 checks passed

horgh deleted the greg/billing-phone-verification-inputs branch October 20, 2026 21:22

Conversation

oschwald commented Oct 9, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

horgh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants

oschwald commented Oct 9, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Oct 9, 2026 •

edited

Loading